Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README: Define "unspecified", "undefined", and "implementation-defined" #311

Conversation

wking
Copy link
Contributor

@wking wking commented Sep 14, 2016

I had been unaware of formal distinctions between these terms until @stephenrwalli called it out in the context of his suggestion to use “implementation defined” for uploading application/vnd.oci.image.layer.nondistributable.tar+gzip. I couldn't find anything as compact as RFC 2119 around this idea, but linking to a section of the C99 rationale seems reasonable enough. The PDF I'm linking is “Rationale for International Standard - Programming Languages - C Revision 5.10 April-2003” and the referenced content appears in section 3.

The “rationale for the C99 standard” link text seems pretty informal, but that's what WG14 uses to refer to the document.

@wking wking force-pushed the unspecified-undefined-and-implemenation-defined branch from 028c05c to 01687e9 Compare September 14, 2016 08:06
@@ -9,6 +9,8 @@ The combination of the image manifest, image configuration, and one or more file

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997).

The keywords "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][unspecified].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"unspecified" is an awkward name for a link (especially a reference one because at first blush it looks like a placeholder) - can you call this c99rationale or similar?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On Wed, Sep 14, 2016 at 02:58:04AM -0700, Jonathan Boulle wrote:

+The keywords "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][unspecified].

"unspecified" is an awkward name for a link (especially a reference
one because at first blush it looks like a placeholder) - can you
call this c99rationale or similar?

In case we ever link to another part of the c99 rationale, I've gone
with c99-unspecified in 01687e92d49333.

I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.

  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

Also update the layer.md instance to use the C99 standard's hyphenated
form.

[1]: opencontainers#233 (comment)
[2]: opencontainers#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <wking@tremily.us>
@wking wking force-pushed the unspecified-undefined-and-implemenation-defined branch from 01687e9 to 2d49333 Compare September 14, 2016 15:12
@jonboulle
Copy link
Contributor

jonboulle commented Sep 14, 2016

lgtm

Approved with PullApprove

1 similar comment
@philips
Copy link
Contributor

philips commented Sep 14, 2016

lgtm

Approved with PullApprove

@vbatts vbatts merged commit d138321 into opencontainers:master Sep 15, 2016
@wking wking deleted the unspecified-undefined-and-implemenation-defined branch September 21, 2016 20:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants